Add extends property for configuration inheritance - #772
Sam Frost (SamuelFrost) wants to merge 4 commits into
Conversation
Document and schema-enable the extends keyword from devcontainers#22, merging referenced files with the existing image metadata merge logic.
|
@microsoft-github-policy-service agree |
Schema and reference docs for combine (default) and override merge when using extends, aligned with the Dev Container CLI behavior.
Align spec and schema with spread semantics: set properties replace the inherited value entirely; omitted properties keep the chain below.
|
Requesting review from Chuck Lantz (@Chuxel) joshspicer Samruddhi Khandale (@samruddhikhandale) Christof Marti (@chrmarti) and @devcontainers/maintainers when you have bandwidth. This documents and schema-enables configuration inheritance for spec#22 ( Docs:
Note on semantics: default I'd appreciate review on normative wording and whether anything should change before or in parallel with CLI PR #1306. vscode-docs follow-up can wait per CONTRIBUTING guidelines. Thanks! |
2 participants
Summary
Teams sharing a codebase often need slightly different
devcontainer.jsonsettings without copying the whole file. Issue #22 proposed anextendsproperty for that.This PR adds
extendsandextendsMergeModeto the schema and reference docs so one configuration can inherit another JSON or JSONC file in the same repository, with selectable merge behavior.Companion Dev Container CLI implementation: devcontainers/cli#1306
Properties
extendsextendsMergeMode. Not present in merged output. Absolute paths and URLs are not supported. Referenced files may themselves useextends.extendsMergeModecombine(default) oroverride. Read from the file that declaresextends. Not present in merged output.Merge behavior
Use
combineon a layer for additive object/array merging; useoverridefor a thin layer that replaces specific properties.combine(default)Same merge logic as image metadata: array union where applicable,
hostRequirementsmax, object maps merged per key with the current file winning conflicts, booleaninit/privilegedtrue if any side is true, scalars last-wins, and so on.overrideEach top-level property set on the current file fully replaces values from the extends target; omitted keys keep the resolved target's values.
Changes
schemas/devContainer.base.schema.json:extends,extendsMergeMode.docs/specs/devcontainerjson-reference.md: general properties table entries, Configuration inheritance section (examples from spec#22,combine/overridesemantics).docs/specs/devcontainer-reference.md: one sentence in the merge-logic table notes linking inheritance to the same merge rules (Configuration inheritance).Technical choices (from CLI #311 review)
Issue #22 originally described Docker Compose–style deep merge. Review of CLI PR #311 settled on image metadata merge for the default (
combine) path. Nestedextendsis allowed; cycles, absolute paths, and URLs are not. Cross-repository references remain future work per spec#22.Test plan
extendskeyword cli#1306Additional decisions (beyond original spec#22 / CLI #311 review)
extendsMergeModealongsideextends9f8d6d7overridedocumented as full top-level replace (spread semantics), not shallow merge of object maps /hostRequirementsc221072Full branch commit series:
1b7c38d→9f8d6d7→c221072.Follow-up
CONTRIBUTING.mdasks for a PR against the devcontainer.json reference in vscode-docs once maintainers are on board.Finalizes spec#22.